package org.xx.armory.db;

import java.sql.Connection;
import java.sql.SQLException;

/**
 * 用于获取数据库连接的引用。
 * <p>只有需要使用数据库连接时，{@link ConnectionRef}才会获取可用的连接，所以使用{@link ConnectionRef}代替{@link Connection}可以避免过早的创建数据库连接。</p>
 */
public interface ConnectionRef
        extends AutoCloseable {
    /**
     * 获取当前数据库连接并执行SQL语句。
     *
     * @param action
     *         待执行的SQL操作。
     * @param <R>
     *         SQL操作返回的结果类型。
     * @return SQL操作返回的结果。
     * @throws SQLException
     *         执行SQL操作时出错。
     */
    <R> R execute(SqlAction<R> action)
            throws SQLException;

    /**
     * 关闭当前存在的数据库连接，如果当前不存在数据库连接则什么都不做。
     *
     * @throws Exception
     *         如果关闭数据库连接出错。
     */
    void close()
            throws Exception;
}
